ZXemul version 1.0
==================

ZX Spectrum 48k emulator for Psion 3a, 3c and 3mx palm computers.

- compatible with Psion 3a, Psion 3c and Psion 3mx
- highly optimized emulation core written completely in assembler
- undocumented Z80 instructions and R register fully supported
- 3 color modes (INK, Black & White, Gray)
- 3 screen mapping modes (Pan, Shrink, Fit)
- simulation of Kempston, Cursor, Fuller and Sinclair joysticks
- 70-110% speed of original ZX Spectrum on Psion 3mx
- loading and saving of .Z80 and .SNA file formats
- built-in Spectrum keyboard layout help screen for BASIC fans


1. LEGAL NOTICE
---------------

This program comes with no warranty of any kind. In no event will the
author be liable for any damages resulting from the use of this program.

ZXemul is freeware. This mean that you can use it completely for free,
and you may copy and distribute copies of ZXemul in the same form as you
received it, without any file being removed, altered or added.


2. INSTALLATION
---------------

You should backup all your Psion data prior to running the ZXemul (it is
always a good idea to backup regularly, regardless if you use ZXemul or
not). Although carefully programmed and tested a lot, internal
application error may result in a hardware reset, loosing all your Psion
files as a result.

1) Copy ZXEMUL.APP into \APP directory on any of your Psion disks.
2) Create directory \APP\ZXEMUL on the same disk where ZXEMUL.APP was
   copied and copy the files ZXEMUL.LDD and ZXEMUL.ROM into it.
3) Create directory \ZXS on any of your Psion disks and copy here all
   .Z80 and .SNA files you want to run. This is also the folder where
   saved snapshots goes by default.
4) Use Psion+I from the System screen to install the ZXEMUL.APP
   application.

To run ZXemul, you will need about 115kB of free memory.

ZXemul won't run on Sienna, Workabout or plain Series 3 computers, nor
be functional on any of the PC emulators. The Psion 3a and 3c computers
are supported, but the emulation will run about 3.5 times slower than on
Psion 3mx due to the slower CPU clock frequency on these models.

Please note that no Z80 or SNA files are included in this package. Use
the well known Internet archives full of Spectrum games and
applications.


3. ZXEMUL SCREEN
----------------

When started, ZXemul creates two status windows. The left status window
shows selected screen mapping mode, the portion of the Spectrum screen
shown on the Psion display and the selected joystick emulation. The
right status window is shows the current open file, selected color mode
and other system information like the current time and battery status,
etc.The middle part of display shows the 256x160 pixel representation of
the Spectrum screen, with possible border on the left and right.


4. COLOR MODES
--------------

There are three different color modes. They differ in the quality, way
they work and the screen refresh speed. These are:

Ink mode    - Only INK part of Spectrum screen is shown as black on
              white. The attributes are ignored and no border is drawn.
              This is the fastest mode.

B&W mode    - Two color mode. Darker color in each attribute is mapped
              into black, the other one to white. Although slower than
              Ink mode, this mode is a good quality/speed compromise.

Gray mode   - Three color mode. Eight Spectrum colors are uniformly
              mapped into black, gray and white. It is possible that
              some details on the Spectrum screen will not be visible on
              Psion as the near Spectrum colors may be mapped into the
              same color on Psion. This is the slowest mode.

Use diamond key or Psion-M to switch between the color modes.


5. SCREEN MAPPING MODES
-----------------------

The Psion screen is taller than the Spectrum one. Thus, some kind of
screen mapping is necessary. ZXemul offers three different modes.
Updating the screen takes the same time regardless of the mapping mode
selected.

Pan mode    - Only a part of Spectrum screen is shown. The screen is not
              shrunk. Pan the window up and down using Psion and
              arrows to see the remaining 32 rows. Left status window
              shows the actual position of the Psion screen in the
              Spectrum one.

Shrink mode - Each eighth pixel row is omitted to shrink the screen with
              minimal impact on the image quality and text readability.
              However, still 8 rows is not visible, so you had to pan.

Fit mode    - The Spectrum screen is even more shrunk by removing
              additional 8 rows to fit completely into the Psion
              one. No panning is required.

Use Shift and diamond key or Psion-M to switch between mapping modes.


6. KEYBOARD
-----------

All the 40 Spectrum keys are mapped onto the corresponding Psion keys.
Use the left Shift as CAPS SHIFT, the right one as SYMBOL SHIFT. The
rest of Psion keys not found on the Spectrum is mapped as best as
possible into a combination of the corresponding Spectrum keys.

For example, to issue DELETE, you can use either left Shift and 0, or
just press the Delete. This work also for comma, period, plus, minus,
asterisk and slash symbols and also for the shifted variants on these
keys. So, pressing a Shift and period key on Psion will be mapped into
pressing SYMBOL SHIFT and T key on Spectrum, with the desired >
character on output.

If you intend to work in BASIC, please note that Spectrum had various
cursor modes, outputting different characters and keywords for the same
key based on the current mode. Use the Psion+M key to show a Spectrum
keyboard layout with all the keywords.

If activated, the joystick simulation is mapped onto the arrows, with
the fire on the Tab key. You can use Cursor joystick to conveniently use
arrows when editing in BASIC.


7. FILE FORMATS
---------------

You can save and load the complete emulator state into Z80 and SNA
memory snapshots file formats. Choose the appropriate format extension
in the Open or Save dialogs. If possible, prefer using the Z80 file
format, as it is often smaller than corresponding SNA file.

Note that only Z80 files will appear under the ZXemul icon in the System
screen. However, you can create a new list for the ZXemul application to
view the SNA files too.

Only ZX Spectrum 48k snapshots are supported.

Use the New file command from the File menu to start a new emulation
under the ZXEMUL name.


8. PREFERENCES
--------------

In the Preferences dialog (invoked via Psion-Q) you can change some
settings controlling the emulation. Please change them carefully as
improper values may lead to slowed down or not functioning emulation.

You can choose between the Kempston, Sinclair 1, Sinclair 2, Cursor and
Fuller joysticks simulation or switch the joystick simulation off.

Set Key clicks on if you want to hear a standard Psion click on each key
pressed. Please note that this may not correspond to a new key sensed by
the emulated program, especially if the clicks are autorepeated. The
clicking may be also confusing and annoying during the gameplay.

The Screen refresh parameter sets the number of INT interrupts (on ZX
Spectrum generated 50 times per second) between the Psion screen is
updated. Increasing the value will release some time for the emulation
otherwise spent in the screen redrawing, but may jerk animations.

The Ops per INT parameter specifies number of emulated Z80 instructions
between the INT interrupt is generated. On the real Spectrum this value
varies depending on the time complexity of the instructions being
executed. Setting the value higher will increase the emulation speed a
bit as the interrupt handler routines will not be called so often, but
the keyboard response may suffer.

The default and well proven values of Screen refresh and Ops per INT are
4:5000 for Psion 3mx and 6:2000 for Psion 3a/c.

If ROM patch option is set on, the original Spectrum ROM is patched to
prevent ROM code from modifying itself. The ZXemul does not test the
memory writes against possible ROM area during the emulation due to the
performance reasons. If the ROM were not patched, the often called BASIC
implementation routines would rewrite some important areas in the ROM.
Switch the patching off only if you experience a compatibility problems
with programs checking the ROM. You must restart ZXemul to apply the
change of this setting.


9. OTHER
--------

You can reset the emulator by pressing Psion-R. A non-maskable interrupt
(NMI) can be generated by pressing Psion-I. Please note that due to the
bug in the Spectrum ROM it will have the same effect as resetting the
Spectrum.

To pause the emulation, press Esc key. Any key then will run the
emulation again. The emulator is paused also when menu, dialog or help
windows are active or the when the ZXemul is switched to the background
(when user switches to another running application).

Be aware that the emulation is highly CPU intensive process, thus
consuming the battery power a lot (about 3 times more compared to normal
Psion applications), regardless of the activity of the emulated program.
Always pause the emulator if you are temporarily not using it.


10. CONTACT INFO
----------------

Any questions, comments and suggestions are highly welcomed. To contact
me, send an e-mail to freeman@mail-box.cz or visit my web pages at
http://freeman.web2001.cz. Help me to further improve the ZXemul!

Designed, developed and tested from July to December 2000 in Prague,
Czech Republic. (c) 2000 Radek Svoboda alias Freeman


11. ACKNOWLEDGEMENT
-------------------

I would like to thank the following people and companies. Without their
help, support and inspiration, the ZXemul either would not exist or be
born in much bigger pain:

Matt Gumbley	- This man tried to emulate ZX Spectrum on Psion 3a
                  years before me. His page about that attempt was a
                  good challenge for me.

Szeredi Miklos  - Although never contacted, his SpectEmu emulator for
                  Linux gives me a good starting point on how to write
                  an efficient Z80 emulation in the assembler.

PointX company	- For the SIBO C SDK support provided.

Cade Roux       - For the big help with HWIM programming problems. One
                  of the rare HWIM skilled programmers in the
                  world.

Pavel Cejnar	- First person dare enough to test the ZXemul on his 3a.

Olda Palenicek	- For the great discussion about the emulation, life,
                  and everything.

And many others ...

